Description of external resource file format

Introduction

An external resource file (.fpcres extension) provides resource support for those systems where a resource format suitable to be embedded in an object file isn't available.

The file format is designed in a way similar to other internal resource formats. The file is opened at program startup and is mapped in the program address space. Offsets in the file are easily converted to pointers at runtime since those offsets represent a displacement from a base address (the starting address where the file is mapped). Differences from an internal file format hence lie in the fact that resources aren't mapped in the program address space by the program loader but by Free Pascal RTL, and data must be accessed with a displacement mechanism instead of absolute pointers.

For internal resources details, see Format of resources in object files

File layout

An external resource file consists of these parts:

• The initial header, containing various file information
• The resource tree, in the form of nodes
• The string table, which can be optional
• The resource data

The header is made up by initial header, resource tree and string table (if present).

Conventions

In this document, data sizes are specified with pascal-style data types. They are the following:

Byte order used in the file is specified in the initial header.

All data structures in the file must be aligned on qword boundaries.

The initial header

An external resource file starts with this header:

Note that byte order of the file can be read in the endianess field of the header. All data fields longer than a byte are written with the byte order specified in endianess.

If no resource name or type is identified by strings, string table is optional. When this is the case, nodesize and hdrsize have the same value.

The resource tree

Immediately following the initial header, the resource tree comes. It is made up by nodes that represent resource types, names and language ids.

Data is organized so that resource information (type, name and language id) is represented by a tree: root node contains resource types, that in turn contain resource names, which contain language ids, which describe resource data.

Given a node, its sub-nodes are ordered as follows:

• First the "named" nodes (nodes that use a string as identifier) come, then the id ones (nodes that use an integer as identifier).
• Named nodes are alphabetically sorted, in ascending order.
• Id nodes are sorted in ascending order.

In the file, all sub-nodes of a node are written in the order described above. Then, all sub-nodes of the first sub-node are written, and so on.

Example:

There are three resources:

1. a BITMAP resource with name MYBITMAP and language id $0409
2. a BITMAP resource with name 1 and language id 0
3. a resource with type MYTYPE and name 1 and language id 0

Nodes are laid out this way (note that BITMAP resources have type 2):

root | MYTYPE 2 | 1 | 0 | MYBITMAP 1 | $0409 | 0

That is, types (MYTYPE is a string, so it comes before 2 which is BITMAP), then names for MYTYPE (1), then language id for resource 3 (0), then names for BITMAP (MYBITMAP and 1), then language id for resource 1 ($0409), then language id for resource 2 (0).

Node format

Note that all offset are always relative to the beginning of the file.

If the node is identified by a string, nameid is an offset to the null-terminated string holding the name. If it is identified by an id, nameid is that id. Language id nodes are always identified by and ID.

ncount is the number of named sub-nodes of this node (nodes that are identified by a string).

idcountsize is the number of id sub-nodes of this node (nodes that are identified by an integer id). For language id nodes, this field holds the size of the resource data.

subptr is an offset to the first subnode of this node. Note that it allows to access every subnode of this node, since subnodes of a node always come one after the other. For language id nodes, subptr is the offset to the resource data.

The string table

The string table is used to store strings used for resource types and names. If all resources use integer ids for name and types, it may not be present in the file.

The string table simply contains null-terminated strings, one after the other.

If present, the string table always contains a 0 (zero) at the beginning. This way, the empty string is located at the offset of the string table (whose value is held in nodesize field of the initial header).

The resource data

This part of the file contains raw resource data. As written before, all data structures must be aligned on qword boundaries, so if a resource data size is not a multiple of 8, bytes of padding must be inserted after that resource data.